Content of this chapter is also included inside of the~application. It is
available in the~form of formatted HTML help with searching, indexing and
navigation capabilities.

\section{Introduction}
This document describes basic usecases and procedures of the~software part of the~Robot Playground project. RobotPlayground project was designed by Lukas
Zaruba in 2012. The~application provides robust and extendable environment for
driving and/or simulation of robotics or any other hardware. It can be used for
school projects, hobbyists or to verify some ongoing concepts. It provides core
runtime and some default implementations out of the~box.

Every user who is at even minimally capable of programming is strongly
suggested to explore the~source code available and if he needs implement his own
functions, features, Modules or any other useful part. Whole nature of this
project is to create the~platform rather than complete solution. Complete
solutions suffers from the~idea of being complete. There is always something
missing for some users. This way, you are free to implement whatever you like.

\section{Installation} The~application can be installed by simply unzipping the~archive into the~desired directory. Then it can be executed using the~native launcher. Its name
depends on the~platform you are using.

To run the~RobotPlayground, you have to have the~Java 7 SE installed on your
computer. You can obtain Java from the~\url{http://java.oracle.com}.

\section{Structure of the~Usage} The~RobotPlayground is based on the~``project oriented structure''. This layout
allows users to organize separate projects with different Sessions, logs, source
files or any other resource.

Project is the~most basic structure of the~application workspace. Every project
can carry even more than one Session but should be a~representation of a~logical
division of the~data.

To clarify it, projects are obligatory in the~layout of the~workspace. If you
want to start creating any structures, you need to create at least one project
first. This procedure will be covered later into details. Projects can be also
obtained using import from archives or folders.

\begin{center}
\includegraphics[width=15cm]{../guideImages/robotPerspective}
\end{center}

After having a nice project, a Session can be created. The~Session is
a~container that provides configuration capabilities and holds together sets of different
elements. These elements will be described in detail later.

When the~Session is ready in the~state we want to have it, we can execute the~session. Execution of the~Session doesn't really affect the~original session in
any way. It only produces log results and may produce any other outputs
depending on the~type of elements stored in the~Session.

This description is a~little abstract. This is due to the~fact that the~whole
project doesn't have some standard shape and most of the~details depend on the~configuration. Later in the~text these details will be covered as much as
possible.

\section{Manipulating Projects}
As stated before, project is the~smallest possible element in the~root of the~workspace. This statement actually implies that there are bigger structures.
These structures are called working sets and will be covered later.

Select descriptive names for your projects. In some time, projects might pile up
in the~workspace and ``test'' or ``experiment'' which might be good quick names
at the~beginning will become a~problem later.

\subsection{Create a~New Project}
New project creation can be started by several procedures. These procedures are
equivalent and which you will use depends entirely on your preferences.

\paragraph{Right-click} to the~are of navigator on the~left side of
the~workspace and select ``New\ldots''$\to$\-''Project''. You will be asked for
the~type of project. Select ``General''$\to$``Project''.
\paragraph{Clicking on the~``New'' icon} up to the~navigator area. Wizard will
come up. Do the~same selection as described in the~previous paragraph.
\paragraph{Clicking on the~arrow on the~``New'' icon} up to the~navigator area
and selecting ``Project''. This is actually the~most convenient way.

After the~start, Wizard asking for the~name of the~project will come up. Fill
the name. Rest of the~settings are intended to be used by experienced users and
are beyond the~scope of this text. Finish the~wizard. Now you should see your
new project in the~navigator area on the~left side.


\subsection{Import Existing Project}
You can import existing projects into your workspace. This feature can be used
for moving of the~project from one computer to another or to pass the~project to
somebody else. Projects for importing can come in the~form of archives or can be
in the~form of a~folder.


Import can be invoked by right-click into the~navigator area and selecting
``Import\ldots''. In the~offer select ``Existing Projects Into Workspace''
option. The~import options page will come up. In the~top part of this page you
can select whether you want to import archive or content of a~folder. Select
what suits your needs. Just note that when selecting folder, you should select
parent folder of the~project you want to import.

\begin{center}
\includegraphics[width=8cm]{../guideImages/import}
\end{center}

In the~area in the~middle of the~page, list of possible projects to be imported
will show. Check projects you want to import and finish the~wizard. New projects
will show up in the~navigator view.

Important notice. Import only projects created by the~same version of the~application. Otherwise it might not work.

\subsection{Working Sets}
Concept of working sets allow user to group projects together in some kind of
topics or themes. It can be achieved by clicking on the~small arrow (shown on
image) in the~navigator area and selecting ``Select Working Sets\ldots''.

Here you can select an~existing working set or create a~new working set by
clicking on ``New\ldots'' button. You will be asked to check which projects you want to
add to the~working set.

\begin{center}
\includegraphics[width=15cm]{../guideImages/WorkingSets2}
\end{center}

Finish the~wizard and situation should look like on the~image. If not, try to
open the~arrow and go to the~``Top Level Elements'' part and select ``Working
Sets''. Please note that one project can be located in the~multiple working
sets.

\begin{center}
\includegraphics[width=10cm]{../guideImages/workingSets}
\end{center}

\subsection{Export Project}
Project can be exported by right-click in the~navigator area and selecting
``Export\ldots. Under the~``General'' you can select either ``File System'' or
``Archive File''. In both variants, you can finish the~selection of elements to
be exported and after filling the~path to the~archive or folder you can finish
the wizard. Projects can be selected in the~navigator view to save you some time
while selecting them in the~export dialog. Data exported using this feature can
be used for importing of the~data as described before.

\section{Manipulating a~Session}
As discussed before, Session is the~central element of the~works inside of this
application. Its purpose is to let you put together Modules, Devices and others
to be able to configure them together and then execute. You can add following
four types of elements to the~Session. To see how the~Session looks refer to the~first application image.

\textbf{Device} is an~abstraction of the~real HW device or its simlution. It can
represent anything from just the~point on map to the~complex robot. It provides
communication layer if necessary and encapsulates functionality of the~device
itself. You can imagine it as a~firmware of some kind. Unless you develop your
own Modules, you will not come into touch with the~API of the~Device much.
You just need to add the~Device into the~session and configure it properly if
needed. Each type of Device might have its own configuration. Please refer to
its documentation for details.

In the~previous paragraph, \textbf{Module} was mentioned. If a~Device represents
firmware, Module would be a~Driver. It can work with a~Device (or it might be
standalone in some cases) and publishes functionality of the~Device (or itself).
The~capabilites should be kind of high-level. Nothing like send a~byte to the~device but more of a~turn left command. It provides functions that can take zero or more arguments and can return a~value of any kind. These functions should be
documented in the~concrete Module documentation. Modules can communicate between
themselves (using API access).
 The~confusing part for a~beginner might be a~\textbf{Monitor} section. Monitor
can be used for interpretation of the~state of Modules. It is not intended to be used by
Programs. It is more of the~UI thing. In the~Dummy Suite you will see
the~Monitor that controls position of the~Device and checks it against the~obstacles.
If the~rules are broken, this Monitor stops the~simulation. Important is that
this functionality is taking place outside of the~Dummy Device or its Module. It
can be described as independent judge. As I mentioned, it can also bring UI
features. Dummy Monitor provides view of a~map on which you can see obstacles
and movements of the~Dummy Device during the~running of the~session.

Last but not least is the~Program. \textbf{Program} is something that brings the~life to the~pile of configurations. A~Program can be in the~form of any implemented
language. It gets executed and receives access to Modules. Using the~language,
logic can be implemented. It can read sensor values from Modules and react
properly by sending a~command to another Module or any other action. There can
be more than one Program in the~Session. All these Programs get executed in
parallel and manipulate Devices concurrently. Make sure that Modules and Devices
you are using can handle that.
\section{Session Creation}
Now you are excited to start creating your own Session. Go to some of
the~projects created by the~previous text. Again there is more than one way of how to create a~Session. These steps are similar to the~way how the~project is
created. The~most convenient way is to use the~arrow next to the~``New'' icon
and select ``New Session''. If it is not shown due to the~current selection, you
can use the~generic offer of new elements and select ``Robot Playground''$\to$``New Session''.

\begin{center}
\includegraphics[width=6cm]{../guideImages/newSession}
\end{center}
 The~wizard will come up. Fill the~name and if you wish also the~note. After you
are done, finish the~wizard. Your new Session will open in the~editor.

\section{Adding an~Element}
On the~right side of each section of the~Session editor, you can see a~green
plus button. If you click on it, you will be offered with available elements of
that type. Select the~one you want. It will be added to the~Session and if it
has some configuration, it will start. For the~steps of the~configuration,
consult the~documentation related to the~element.

\section{Configuration}
As stated before, some of the~elements might be configurable. Sometimes, it is
one line, sometimes you have to select a~file from workspace and sometimes, it
can be a~very complex wizard. Type of the~configuration depends on the~element
you are adding.

You can say if the~element is configurable by checking the~black cogwheel in
the~top corner of the~element. If it is dark, you can click it to reconfigure
the~element. If it is gray, it cannot be configured.

\begin{center}
\includegraphics[width=3cm]{../guideImages/Icons2}
\end{center}

\section{Removing an~Element}
Element can be removed from the~Session. Of course it can cause an~inconsistency in the~validation. You can remove an~element by using the~red icon
in the~top corner. After acknowledging of the~request, it will be gone.

\section{Element Validation}
Each element of the~session is validated every time some change occurs. If
the~validation was a~success, green icon will be shown in the~left top corner of the element. It can happen that the~validation is not successful. In this case red
exclamation mark is shown. If you hover the~mouse over the~icon, popup with
the~problem description will appear so you can fix it.

\begin{center}
\includegraphics[width=3cm]{../guideImages/Icons1}
\end{center}

There can be many sources of unsuccessful validations. It can be caused by
missing required Modules or Devices, problems with connection to the~device or
syntax errors in the~program. Anyway the~Session cannot run until you fix
the~problems.

\section{Navigating to the~Element Content}
Some of the~elements that are based on the~resources located in the~workspace
can navigate to these resources by double-click on the~icon of the~element.
Internal editor should be opened in the~editor area.

\section{Running a~Session}
And now the~best part. You have your Session ready, Devices are waiting, Modules
are configured and Programs are complete. You can notice a~green play like icon
in the~toolbar when you select your Session editor. Save the~Session and press
the button. 

\begin{center}
\includegraphics[width=1cm]{../guideImages/runButton}
\end{center}

You will be switched to the~run perspective - more about perspectives later.
Here the~Session editor will get smaller and console will appear. If you have
any Monitor that provide UI output it should appear next to the~console or in
the~same stack, depending on the~last layout. Believe it or not, your application
is now running. Please notice that one Session can be executed only once at a~time. More Session can run concurrently, for example if you have multiple robots
and they should interact.

\begin{center}
\includegraphics[width=15cm]{../guideImages/runPerspective}
\end{center}

\subsection{Working with Console}
Console shows anything that Modules, Devices, Monitors or Programs have to say.
Mostly it will remain empty until there is some problem or you do the~logging in
the~program. You can notice several icons on the~console toolbar. Using the~stop
icon, you can stop the~execution. A~stacktrace will be logged to show you where
the~stop came from. Do not panic, this is normal behavior.

\begin{center}
\includegraphics[width=7cm]{../guideImages/Console}
\end{center}

Using the~icon with the~blue screen, you can switch to another console.
All runs from the~start of the~application stays in the~console stack.

Using the~icon with the~small star, you can open new console view. This feature
is aimed to advanced users.

Using the~icon with the~black cross, you can clear the~console. If you have
console full of information and you want to continue fresh, use this action.

Icon with small yellow lock can be used to freeze the~console. New information
will be still appended at the~end, but console will not scroll down
automatically. This way if there is something you want to examine without
stopping of the~session, user can lock the~console on the~current position.

\section{General Navigation Through the~Application}
As you probably already found although this application looks empty at the~first
glance, it is very capable and flexible. Try moving views or editor by their
fold. You can move it to another part of the~screen. By moving of the~view to
the~corner of its area, you can place multiple views next to each other. This
way you can for example watch the~console together with the~map at once.
Double-click the~fold of the~view or editor to bring it to the~full application
view.

If you want to open some closed view, go to the~menu and select
the~``Window''$\to$''Show View''.

\subsection{Perspectives} The~word perspective was mentioned before. Perspective is a~layout of views and
editor area, nothing more. Although it might seem unimportant, it can be very
useful. There are two perspectives prepared for you. One with the~robot as a~symbol is intended to be used for creation and tuning of Session. The~second one
with the~play symbol is intended to be used when running a~Session. Switch these
two often to get the~most usable IDE.

\begin{center}
\includegraphics[width=1.5cm]{../guideImages/perspectives}
\end{center}


If you mess up the~perspective, you can always go to the~``Window''$\to$''Reset
Perspective\ldots'' action. Perspective will get into its original shape. If you
accidentally close a~perspective, it can be opened again in
the~``Window''$\to$''Open Perspective''.

\subsection{Multiple Editors}
Whether you debug your code, compare logs or copy-paste something, it can be
useful to have two editors next to each other or one above another. This can be
achieved easily by dragging the~editor fold to the~side of the~editor
area (or top or bottom) until the~small black arrow will appear. Then editors
will appear in the~new layout. Now you can drag'n'drop editors between editor
stacks. Try using the~right button on the~fold of an~editor to check all
the~options.

\begin{center}
\includegraphics[width=15cm]{../guideImages/twopanels}
\end{center}

\subsection{Following the~Selection}
Sometimes you can move between the~resources in the~workspace so fast that you
loose a~track where you are. There is the~synchronization tool to keep you on
track. You can switch it on using the~two arrow icon at the~top of the~navigator
area. From now on whenever you focus on an~editor, its position in the~workspace
will be selected in the~navigator view.

\begin{center}
\includegraphics[width=4cm]{../guideImages/navigator}
\end{center}

\section{Dummy Suite}
Dummy Suite is a~reference implementation of all kinds of elements that can be
added to the~session and much more. Its purpose is to provide an~example to
the~developers on how to contribute new elements. But it is not the~only
purpose. It is built around a~virtual device that can rotate and move in
the~virtual space. As simple as it sounds it can easily represent a~real
robot.
The~Suite also provides Modules to manipulate the~Dummy Device and monitor it. To be able to provide whole space exploring capabilities, obstacles on the~map and some kind of radar is implemented.

\subsection{Dummy Device}
Dummy Device is as described a~virtual device. It holds its x and y coordinates
in the~2D space. These coordinates are represented as whole numbers. It also
holds its current direction. Direction is represented as whole number and its
meaning is rotation from the~north direction in degrees. All of these three
attributes can be accessed and changed.

Values are protected for multithread access using a~lock. Before anybody can
change any of the~parameters, the~lock must be obtained otherwise an~error is
thrown. Be sure to unlock in finalize to avoid deadlocks in case of an~exception. Dummy Device is represented by
\texttt{net.\-zarubsys.\-robotplayground.\-dummydevice.\-DummyDevice} class.
Feel free to explore it. Following methods are published (parameters are
omitted as these methods cannot be used directly).
\begin{itemize}
  \item getX
  \item setX
  \item getY
  \item setY
  \item getDirection
  \item setDirection
  \item lockMovementsAccess
  \item unlockMovementsAccess
\end{itemize}

Dummy Device is configured by a~set of initial parameters of x, y and direction.
There should be only one instance of the~Dummy Device in a~Session for now.

\subsection{Dummy Motion}
Dummy Motion Module encapsulates movement capabilities of the~Dummy Device.
Dummy Device is required for this Module to be used. It takes care of
the~abstraction of the~movement from the~direct coordinates to relative
handling of \texttt{move} and \texttt{rotate}. This way it brings the~simulation of the~real device to another level. You cannot just jump to certain position.
You have to get there somehow. While rotation of the~device is basically free
but coordinates are represented as a~whole number, rounding is performed to
evaluate the~target position.

Dummy Motion Module also takes care of locking of the~Device for
changes and handles firing of notifications in the~case of events. 
It can be access under the~id \texttt{dummyMotion} and publishes following
methods to the~API.

\begin{samepage}
\begin{itemize}
  \item void rotate(Integer degrees)
  \item void move(Integer distance)
\end{itemize}
\end{samepage}

There should be only one instance of Dummy Motion Module in a~Session for now.
It will automatically be assigned to the~Dummy Device. There is no conifguration
for Dummy Motion.

\subsection{Dummy Telemetry}
Dummy Telemetry Module represents a~very thin envelope encapsulating read-only
access to the~Dummy Device. It publishes following methods to the~API.

\begin{itemize}
  \item getX()
  \item getY()
  \item getDirection()
\end{itemize}

It can be accessed under id \texttt{dummyTelemetry} and doesn't require any
configuration. There should be only one instance of the~Dummy Telemetry in a~Session. It will be assigned automatically to the~Dummy Device instance.

\subsection{Dummy Obstacles}
Dummy Obstacles Module is used to place obstacles into the~virtual 2D space to
have some fun. Map of obstacles is loaded from a~text file. Each line of the~file represents a~row on the~map. Each line has to contain same count of
characters. Only allowed characters are \texttt{x} and \texttt{o} representing
obstacle and free place respectively. White spaces, empty lines or any other
elements are not allowed. Count of lines and length of lines represent the~size
of the~map. It is recommended to put obstacles on the~borders because borders
are the~prohibited area for the~Dummy Device although this logic is not
present in this Module. Example of the~map can be found in the~default workspace.

Besides the~obstacles specification this Module also provides some ``radar''
capabilities. Its \texttt{boolean isObstacleAhead(Integer x, Integer y,
Integer direciton)} provides information about possibility to move one step
ahead in the~given direction. Method of calculation of the~final destination is
the same as in the~Dummy Motion Module. This Module can be accessed using id
\texttt{dummyObstacles}.

Dummy Obstacles Module is configurable. Its configuration wizard will ask you
for an~existing file from the~workspace. This file can be located in another
project than the~Session but it must exist by the~time you want to add the~Module to the~Session. Its filename extension must be \texttt{.map} otherwise it
will not be found. 
This Module provides capability of resource opening. If you double-click on the~icon you will be brought to the~text editor in which you can edit the~map.
Please note that by right-click on the~gray edge of the~editor you can turn on
line number which might be useful. If the~file gets open by some system editor
which is strongly binded to the~\texttt{.map} filename extension, go to the~navigator, right-click on the~map resource and select ``Open With''$\to$''Text
Editor''.

\subsection{Dummy Map}
Dummy Map Monitor holds whole suite together. It listens for messages from the~Dummy Motion Module and using the~Dummy Telemetry together with Dummy Obstacles
it checks whether the~Device is located on the~edge of the~map or at the~obstacle and if so, it stops the~simulation.

Beside the~verification goal, it also provides the~UI representation of the~Suite state. The~representation is in the~form of map on which you can see the~location of obstacles and postion together with direction of the~Dummy Device.
UI representation is the~point of future extension. I'd like to be able to show
also visited squares and the~target.

Dummy Map doesn't have configuration and it is dependent on all mentioned
Modules - Dummy Motion, Dummy Obstacles and Dummy Telemetry.

\subsection{Joystick Device}
There is another Device available. It is the~Joystick Device. It can access HW
joysticks and read their x and y axis positions together with the~state of
buttons. It is configurable and its configuration depends on the~operating
system you use. On Linux, specify the~path to the~device (Linux device)
representing the~joystick. On Windows, specify the~number of the~device. It will
be most probably number 0. Joystick Device should be only once in a~Session.

Access to the~Joystick Device is realized through the~native libraries. These
libraries are bundled inside of the~application but might require some external
libraries to be available. Mostly on the~Windows, JDK include folder should be
located on the~system path otherwise you might get ``UnsatisfiedLinkException''.
If you are having trouble please let us know using the~reporting capabilities of
the project site and be sure to add as many details about your system, HW and
installation as possible.

\subsection{Joystick Module}
Joystick Module encapsulates capabilities of the~Joystick Device. It provides
the state of the~x and y axis and buttons to the~API so these can be used in
Programs. It can be used in the~endless loop to drive a~device manually. It can
be accessed under id \texttt{joystickModule}. List of published methods follows.

\begin{itemize}
  \item Integer getX() - values between -32768 to 32767
  \item Integer getY() - values between -32768 to 32767
  \item boolean getButton(Integer buttonId) - buttonId between 0..11
\end{itemize}

\section{Script Program}
Script Program comes with the~Dummy Suite although it is not a~direct component
of it. It is a~Program implementation based on the~simple but capable scripting
language. It provides all commonly required capabilities of the~scripting
language and much more. It has been enhanced to provide list and stack
functionalities as these structures are commonly used in the~AI world.

When you are adding a~Script Program to the~Session, you will be asked for the~Script Program. You can either select existing program or create new empty
program. If you select new program, program editor will be opened.

Program Module support resource navigation. If you double-click on the~icon the~script editor will be opened. In this editor you can turn on line numbers by
right-clicking on the~left gray edge of the~editor. This might be useful for
debugging as you get error line number.

Session can contain multiple Script Programs. Each of them will be executed in
parallel. For the~example of how to use the~scripting language, refer to the~BFS
implementation in the~default workspace.

\subsection{General Syntax}
Basic syntax element of this language looks like \texttt{function\-(param1,
param2, param3)}. Multiple statement elements are allowed in one script file.
Spaces between parameters are optional. Basically this is it, it is that easy.
Function is the~first-class object in this language so the~\texttt{param1} can
actually be a~call to another function or literal.

Allowed literals are:
\begin{itemize}
  \item \texttt{'String'} - can contain any character. Escape apostrophes by
  backslash.
  \item \texttt{10} - integer number
  \item \texttt{10l} or \texttt{10L} - long number
  \item \texttt{10.0d} or \texttt{10.0D} - double number
  \item \texttt{10.0f} or \texttt{10.0F} - float number
\end{itemize}

One line comment starts with double slash. Multiline comment starts with the~slash together with star and ends with opposite order. Pretty much the~same like
in Java.

This language doesn't support forming of methods or functions. As a~substitute
there is a~possibility to call another script using the~\texttt{call(path-to-script)} syntax. This facility is intended to be used
against the~code duplication.

\subsection{Variables}
Variables are defined by the~function \texttt{define} or \texttt{defineIfNull}.
Variables are divided into pools. Pools are just a~tool to keep related
variables together. You have to always specify the~pool and the~variable name.
If the~pool doesn't exist it is automatically created. If the~variable hasn't
been used yet, it is created. If it has been used its value is replaced with the~new value (not in the~case \texttt{defineIfNull}). Variables are not typed. You
can change the~type of a~variable even if it has been already initialized with
something else.

You can access or pass the~value of a~variable using function \texttt{value}
with specified pool and variable name.

Variable can be cleared using \texttt{undef} function with the~name of the~pool
together with the~variable name. After this call \texttt{defineIfNull} would
consider the~variable uninitialized and reinitialize it with the~new value.

If you call external script file using \texttt{call} function, variable pools
are shared and any change in the~variables state in the~external file will be
visible when the~call ends.

\subsection{Rules of the~Evaluation}
Only the~syntax is check at the~``compilation time''. References to functions
are checked in the~runtime because they can be redirected to the~API calls.

Functions are evaluated in the~order they are located in the~source file.
Parameters of functions are evaluated in the~time of the~evaluation of the~function they are located in and in the~order of the~paramters. It means that
values and variables are not dereferenced until the~function which they are
passed to is called.

Function can return value. This value might be used as an~input parameter for
another function or omitted.

Syntax checks don't crawl recursively into the~called scripts. They just go
through the~original script. If the~called script cannot be parsed, it will fail in runtime.

\subsection{Errors}
There are basically two types of error in this scripting language. Syntax and
runtime errors.

Syntax errors are usually caused by missing brackets or missing commas. This
language is very verbose and contains a~lot of brackets. Unfortunately at this
moment built in script editor doesn't support showing of bracket pairs or syntax
highlighting. If you get a~syntax error be advised that the~line number might not
be exact but will be most probably one line too far. Sometimes you can get a~message stating that you either missed a~comma or ending bracket at the~last
line of the~complex call. This can be caused by really missing comma separating
one of the~parameters or too much or too less of brackets. The~best way to
verify this is to do the~manual brackets counting. Although it is not a~fancy
technique it actually works.

Runtime errors can mean anything from null or wrong type of a~parameter to
the~internal state of the~application. At this point some of the~Java stacktraces are not shown in the~console. If you get a~simple error into the~console and you
don't have any idea about the~cause of this problem, navigate into the~installation directory of the~application and try to search for log in the~``Workspace'' folder. There you should be able to find a~complex log containing
all the~detailed information including line numbers. If you still cannot figure
out what the~problem is, please let us know using our project website.
\subsection{Basic Functions}
Rules of the~description syntax are following:
\begin{itemize}
  \item \texttt{null} before the~function name means it returns null
  \item \texttt{null} before the~parameter name means that the~function doesn't
  care about its return type
  \item \texttt{?} before the~parameter name symbolises that it is optional
  \item \texttt{\ldots} after the~last parameter means that the~count of
  parameters is infinite. Type of the~parameters is assumed to be equal to the~previous one.
\end{itemize}

\noindent
\texttt{Object eval(null ?command, \ldots)} This function is used as a~block of
statement. It can be empty. Statements are passed as arguments and evaluated in
the order. Do not forget to place commas between the~parameters but not after
the last one. Result of last command is returned.

\noindent
\texttt{null null()} This function always returns null.

\noindent
\texttt{null sleep(int milliseconds)} Stops the~evaluation of the~script for the~given time in milliseconds.

\noindent
\texttt{null log(String severity, String message, \ldots)} Logs the~concatenation
of given messages into the~log under the~severity evaluated from the~first
parameter. Valid values are \texttt{TRACE, DEBUG, INFO, WARNING, ERROR, FATAL}.

\noindent
\texttt{null dump()} Logs into the~log its position in the~file, filename and
content of all variable pools. It is often used for debugging.

\noindent
\texttt{null error(String ?message, \ldots)} Throws exception and stops the~script with the~message containing concatenation of all passed message if any.

\noindent
\texttt{null call(String filePath)} Parses and executes the~script on given
path. The~path is relative to the~application not to the~script currently
running. Assumption about available classpaths cannot be made in here. As
described variable pools are shared with the~calling script and any changes will
be passed to the~calling script once the~called script terminates.

\subsubsection{Variables}
\texttt{Object define(String poolName, String variableName,
Object value)} Defines a new variable or overwrites existing in the~specified
variable pool under the~specified variable name with the~given value. If the~value is null, variable is considered uninitialized after this operation. Passed
value is returned.

\noindent
\texttt{Object defineIfNull(String poolName, String variableName,
Object value)} A~new variable is defined in the~specified
variable pool under the~specified variable name with the~given value if and only
if the~variable specified is uninitialized. If the~value is null, variable is
considered uninitialized after this operation. Passed
value is returned.

\noindent
\texttt{null undef(String poolName, String variableName)} Undefines variable if
it is defined in the~specified.

\noindent
\texttt{Object value(String poolName, String variableName)} Returns a~value
stored under the~specified location or null if the~variable is uninitialized.

\subsubsection{Cycles}
\texttt{null while(boolean condition, null command)} Executes command in
the cycle as long as the~condition is valid. Command is usually
\texttt{eval}.

\noindent
\texttt{Object forEach(String variablePoolName, String variableName,
Iterable iteratedValue, null command)} Iterates over the~instance passed in the~third argument. Current value is always accessible under the~variable pool and
variable name specified in the~first and second parameter. In every iteration
fourth argument is executed. It will most probably be \texttt{eval} function.

\subsubsection{Conditions}
\texttt{null if(boolean condition, null trueCommand, null ?falseCommand)}
The first argument - condition is evaluated and if the result is true, executes
the~command passed in the~second parameter. If it is false and third parameter is present it will be executed. The~other parameter from the~winning one is never executed.

\noindent
\texttt{boolean ifNull(Object value, null trueCommand, null
?falseCommand)} The~first argument gets evaluated. If it is null, second
parameter gets executed.
If it is not null and the~third parameter is present it gets evaluated. The~other
parameter from the~winning one is never executed.

\noindent
\texttt{boolean ifEquals(Object first, Object second, null trueCommand, null
?falseCommand)} Evaluates first and second parameter. If these are equal in the~matter Java equals standard, it executes the~third argument. If they are not
equal or if both or any of them is null and the~fourth parameter is present it gets evaluated. The~other parameter from the~winning one is never executed.

\noindent
\texttt{boolan equals(Object first, Object second)} Evaluates both arguments and
if these are equal in the~matter Java equals standard, it returns true. False is
returned otherwise. Also if both or any of the~arguments is null false is
returned.

\noindent
\texttt{boolean isNull(Object obj)} Evaluates the~object and returns true if it
is null and false otherwise.

\noindent
\texttt{boolean true()} Always returns true.

\noindent
\texttt{boolean false()} Always returns false.

\noindent
\texttt{and(boolean first, boolean second, \ldots)} Evaluates all given
parameters (at least two) and returns true if all of them are true. False is
returned otherwise.

\noindent
\texttt{or(boolean first, boolean second, \ldots)} Evaluates all given
parameters (at least two) and returns true if at least one of is true.
False is returned otherwise.

\noindent
\texttt{not(boolean expression)} Evaluates the~expression and returns negation
of its result.

\subsubsection{Math}
\texttt{Integer abs(Integer value)} Evaluates the~parameter and returns its
absolute value.

\noindent
\texttt{Integer add(Integer first, Integer second)} Evaluates both parameters
and returns first + second.

\noindent
\texttt{Double divide(Number first, Number second)} Evaluates both parameters
and returns first/second. Both parameters are converted to the~double first.

\noindent
\texttt{boolean greaterThan(Number first, Number second)} Evaluates both
parameters and returns true if first > second is valid. False otherwise. Both
parameters are converted to the~double first.

\noindent
\texttt{Double max(Number first, Number second)} Evaluates both given parameters
and returns the~bigger from them. Both parameters are converted to the~double
first.

\noindent
\texttt{Double multiply(Number first, Number second)} Evaluates both parameters
and returns first*second. Both parameters are converted to the~double first.

\noindent
\texttt{Double parseDouble(Object obj)} Evaluates the~parameter and converts it
to string in the~Java fashion. Returns the~double value produced from the~string. If the~string is empty or null 0.0 is returned.

\noindent
\texttt{Integer parseInt(Object obj)} Evaluates the~parameter and converts it
to a~string in the~Java fashion. Returns the~int value produced from the~string.
If the~string is empty or null 0 is returned.

\noindent
\texttt{Integer random(Integer min, Integer ?max)} Evaluates boundaries and
returns random Integer within the~boundaries. If the~max parameter is not
present, only min boundary applies.

\noindent
\texttt{Double round(Integer ?precision, Double value)} Evaluates both
parameters and returns value rounded to the~given precision if present or to the~whole number
otherwise.

\noindent
\texttt{Integer round(Number value)} Evaluates the~value and returns it rounded
to the~Integer.

\noindent
\texttt{Integer substract(Integer first, Integer second)} Evaluates both
parameters and returns first - second.

\subsubsection{Lists}
\texttt{null addToList(List list, Object obj)} Evaluates both parameters and
appends the~obj at the~end of the~list.

\noindent
\texttt{null clearList(List list)} Evaluates the~list and clears it so it will
be empty next time somebody gets it from the~variable pool.

\noindent
\texttt{List createList()} Returns new empty list.

\noindent
\texttt{Object dequeue(List list)} Evaluates the~list and removes and returns
its head.

\noindent
\texttt{Object getFromList(List list, Integer index)} Evaluates both parameters
and returns the~object on the~given index from the~list.

\noindent
\texttt{boolean listContains(List list, Object obj)} Evaluates both parameters
and returns true if the~obj is present in the~list.

\noindent
\texttt{Integer listIndexOf(List list, Object obj)} Evaluates both parameters
and returns the~position of the~obj in list or -1 if it is not present.

\noindent
\texttt{null pushToList(List list, Object obj)} Evaluates both parameters
and pushes the~obj to the~top of the~list as a~stack.

\noindent
\texttt{List removeCollectionDuplicates(Collection list)} Evaluates the~parameter and returns new instance of the~list containing only distinct values
form the~original based on the~Java equals standard. Original list is not
modified.

\noindent
\texttt{boolean removeFromList(List list, Object obj, \ldots)} Evaluates all
parameters and tries to remove all objects from the~list. Returns true if any
object was actually removed or false if no object was present in the~list.

\noindent
\texttt{List reverseList(List list)} Evaluates the~parameter and reverse the~order of its elements. Returns the~reference to the~list alhough the~original is
changed.

\noindent
\texttt{Integer sizeOfList(List list)} Evaluates the~parameter and returns the~count of elements of the~given list.

\noindent
\texttt{List sublist(List list, Integer from, Integer ?to)} Evaluates all
parameters and returns new instance of list created from the~original list as a~sublist between the~given boundaries. From is inclusive and to, if given, is
exclusive. If not given list is taken to the~end.
\subsubsection{Strings}
\texttt{boolean contains(String string, String param1, \ldots)} Evaluates first
parameter and then evaluates iteratively all the~rest of the~parameters until
the first is actually present inside the~first string. If so true is returned.
If none of the~parameters is present in the~first string, false is returned.

\noindent
\texttt{boolean containsIgnoreCase(String string, String param1, \ldots)}
Evaluates first parameter and then evaluates iteratively all the~rest of the~parameters until
the first is actually present inside the~first string. If so true is returned.
If none of the~parameters is present in the~first string, false is returned.
Case of letters is ingored.

\noindent
\texttt{String join(String delimiter, String ?param1, \ldots)} Evaluates all
parameters and return their concatenation delimited by the~first param. Null
values are written into the~result.

\noindent
\texttt{String joinSkipNull(String delimiter, String ?param1, \ldots)} Evaluates
all parameters and return their concatenation delimited by the~first param. Null
values are skipped.

\noindent
\texttt{String lower(String string)} Evaluates the~parameter and returns its
lower case form.

\noindent
\texttt{String substring(String string, Integer from, Integer ?to)} Evaluates
all the~parameters and returns the~substring of the~original string withing the~given boundaries. If the~to value is not passed substring between from and the~end of the~string is returned.

\noindent
\texttt{List tokenize(String string, String ?delimiter)} Evaluates the~parameters and tokenizes the~string using either the~delimiter if given or
default coma or semicolon delimiters. The~result is in the~form of list in the~order of occurrence in the~original string.

\noindent
\texttt{String upper(String string)} Evaluates the~parameter and returns its
upper case form.

Please not that there are more functions related to string manipulation
available. These are related to the~XPath and Regular Expressions and are beyond
the scope of this text.


\subsubsection{Node2D}
Node2D is a~tool that makes the~life of the~map navigation easier. Everything is
about the~object called Node2D. It carries the~x and y coordinates and the~origin node. The~origin node is a~note how did we get to this node. It might be
null.

\noindent
\texttt{Node2D createNode2D(Integer x, Integer y)} Evaluates both given
coordinates and creates an~instance of Node2D class with given coordinates and null value of
origin node.

\noindent
\texttt{Node2D createNextNode2D(Node2D origin, Integer direction)} Evaluates
both parameters and creates new instance of Node2D representing a~node in the~distance of 1 in the~given direction from the~origin node. New node has first
parameter set as its origin.

\noindent
\texttt{Integer getNodeDirection(Node2D node1, Node2D node2)} Evaluates both
nodes and returns calculated direction from node1 to node2 in degrees with 0
directing to the~top of the~map.

\noindent
\texttt{Double getNodeDistance(Node2D node1, Node2D node2)} Evaluates both
nodes and returns calculated distance between these two nodes.

\noindent
\texttt{Node2D getNodeOrigin(Node2D node)} Evaluates the~node and returns value
of its origin or null if none.

\noindent
\texttt{Integer getNodeOrthoDistance(Node2D node1, Node2D node2)} Both
nodes get evaluated and the return value represents calculated orthogonal
distance between the~two.
Orthogonal distance represents number of steps of 1 that need to be taken to get from node1
to node2. In the~other words it is a~sum of absolute values of difference
between the~respective coordinates of both nodes.

